home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Milan_1991 / Devcon91.4 / AppShell / Docs / appshell.doc
Encoding:
Text File  |  1992-09-01  |  63.5 KB  |  2,611 lines
  1. TABLE OF CONTENTS
  2.  
  3. appshell.library/__ACTIVATE
  4. appshell.library/__ALIAS
  5. appshell.library/__CMDSHELL
  6. appshell.library/__DEACTIVATE
  7. appshell.library/__DISABLE
  8. appshell.library/__ENABLE
  9. appshell.library/__FAULT
  10. appshell.library/__RX
  11. appshell.library/__RXS
  12. appshell.library/__STUB
  13. appshell.library/__SYSTEM
  14. appshell.library/__WHY
  15. appshell.library/__WINDOW
  16. appshell.library/__WINDOWTOBACK
  17. appshell.library/__WINDOWTOFRONT
  18. appshell.library/AddFuncEntries
  19. appshell.library/AddFuncEntry
  20. appshell.library/AddProjects
  21. appshell.library/APSHClearPointer
  22. appshell.library/APSHGetGadgetInfo
  23. appshell.library/APSHGetWindowInfo
  24. appshell.library/APSHSetWaitPointer
  25. appshell.library/BuildParseLine
  26. appshell.library/ExpandPattern
  27. appshell.library/FindType
  28. appshell.library/FreeFuncEntries
  29. appshell.library/FreeFuncEntry
  30. appshell.library/FreeParseLine
  31. appshell.library/FreeProject
  32. appshell.library/FreeProjects
  33. appshell.library/GetFuncEntry
  34. appshell.library/GetFuncID
  35. appshell.library/GetFuncName
  36. appshell.library/GetProjNode
  37. appshell.library/GetText
  38. appshell.library/HandleApp
  39. appshell.library/HandleAppAsync
  40. appshell.library/HandlerDataA
  41. appshell.library/HandlerFuncA
  42. appshell.library/IconFromWBArg
  43. appshell.library/LMatchFirst
  44. appshell.library/LockAppInfo
  45. appshell.library/MatchValue
  46. appshell.library/NewProject
  47. appshell.library/NotifyUser
  48. appshell.library/ParseLine
  49. appshell.library/PerfFunc
  50. appshell.library/PrepText
  51. appshell.library/QStrCmpI
  52. appshell.library/RemoveMsgPort
  53. appshell.library/RemoveProject
  54. appshell.library/RenumProject
  55. appshell.library/setup_arexxA
  56. appshell.library/setup_dosA
  57. appshell.library/setup_idcmpA
  58. appshell.library/setup_notifyA
  59. appshell.library/setup_sipcA
  60. appshell.library/setup_toolA
  61. appshell.library/setup_wbA
  62. appshell.library/SwapProjNodes
  63. appshell.library/UnlockAppInfo
  64. appshell.library/__ACTIVATE                       appshell.library/__ACTIVATE
  65.  
  66.    NAME
  67.     ACTIVATE - Restore the GUI to the state prior to DEACTIVATE
  68.  
  69.    SYNOPSIS
  70.     ActivateID    Function ID
  71.  
  72.    FUNCTION
  73.     Restores the GUI to the state prior to deactivating the window.
  74.     This will also reload user preferences.  This function accepts
  75.     no parameters.
  76.  
  77.     As a string command line:
  78.  
  79.         ACTIVATE
  80.         ,
  81.  
  82.     This function is implemented by the IDCMP message handler.
  83.  
  84.    SEE ALSO
  85.     DEACTIVATE
  86.  
  87.    BUGS
  88.     Doesn't handle tools properly.
  89.  
  90. appshell.library/__ALIAS                             appshell.library/__ALIAS
  91.  
  92.    NAME
  93.     ALIAS - Used to build new commands from existing commands.
  94.  
  95.    SYNOPSIS
  96.     AliasID        Function ID
  97.  
  98.    FUNCTION
  99.     This command is used to build new commands from existing commands
  100.     in the function table.
  101.  
  102.     As a string command line:
  103.  
  104.         ALIAS
  105.         NAME,COMMAND/F
  106.  
  107.         NAME    New name to assign to command.
  108.         COMMAND    Command, and its arguments to assign to NAME.
  109.  
  110.    EXAMPLE
  111.  
  112.     The following command line would assign the command OPEN to the
  113.     new command name README, and would use READ.ME as the parameter
  114.     to pass.
  115.  
  116.         ALIAS README OPEN READ.ME
  117.  
  118. appshell.library/__CMDSHELL                       appshell.library/__CMDSHELL
  119.  
  120.    NAME
  121.     CMDSHELL - Open/Close the application command shell.
  122.  
  123.    SYNOPSIS
  124.     CMDShellID    Function ID
  125.  
  126.    FUNCTION
  127.     Opens a console window whereby the user can interact directly with
  128.     the application at a command level.  Allows the user quick access
  129.     to functions or macros that they may use so infrequently that they
  130.     don't wish to bind them to a key, menu or button.
  131.  
  132.     As a string command line:
  133.  
  134.         CMDSHELL
  135.         OPEN/s,CLOSE/s,TITLE/k,SNAPSHOT/s,ACTIVATE/s,FRONT/s,BACK/s,WINDOW/k
  136.  
  137.         OPEN        Open the command shell.
  138.         CLOSE        Close the command shell.
  139.         TITLE        Set the title of the command shell window.
  140.         SNAPSHOT    Save the window size to disk.
  141.         ACTIVATE    Activate the command shell.
  142.         FRONT        Send the command shell to the front.
  143.         BACK        Send the command shell to the back.
  144.         WINDOW        Name of window to open relative to. Defaults
  145.                 to "Main".
  146.  
  147.     As a TagItem attribute list:
  148.  
  149.         APSH_Command, <command>
  150.         where <command> is a valid command, defaults to MH_OPEN.
  151.  
  152.             MH_OPEN    Open the command shell.
  153.             MH_CLOSE    Close the command shell.
  154.  
  155.     This function is implemented by the DOS message handler.
  156.  
  157. appshell.library/__DEACTIVATE                   appshell.library/__DEACTIVATE
  158.  
  159.    NAME
  160.     DEACTIVATE - Shut down the GUI.
  161.  
  162.    SYNOPSIS
  163.     DeActivateID    Function ID
  164.     DeActivateFunc    Function prototype
  165.  
  166.    FUNCTION
  167.     This function will shut down the graphical user interface of the
  168.     application.
  169.  
  170.     This function accepts no parameters.
  171.  
  172.     As a string command line:
  173.  
  174.         DEACTIVATE
  175.         ,
  176.  
  177.     This function is implemented by the IDCMP message handler.
  178.  
  179.    SEE ALSO
  180.     ACTIVATE
  181.  
  182.    BUGS
  183.     Currently, only tracks the main process (no tools or clones
  184.     receive the DEACTIVATE message yet) and the command shell.
  185.  
  186. appshell.library/__DISABLE                         appshell.library/__DISABLE
  187.  
  188.    NAME
  189.     DISABLE - Disable a function and its interfaces.
  190.  
  191.    SYNOPSIS
  192.     DisableID    Function ID
  193.  
  194.    FUNCTION
  195.     This function allows an application or user to disable a function.
  196.  
  197.     If the function is attached to a gadget or menu item, then that item
  198.     is also disabled.  This function does wildcard expansion.
  199.  
  200.     As a string command line:
  201.  
  202.         DISABLE
  203.         NAMES/M
  204.  
  205.         NAMES    The list of valid function names to disable.
  206.  
  207.     As a TagItem attribute list:
  208.  
  209.         APSH_NameTag, <name>
  210.         where <name> is a valid function name.
  211.  
  212.    EXAMPLE
  213.     The following command would disable all commands in an application
  214.     except for those that would be available before the users selects
  215.     NEW.
  216.  
  217.         DISABLE #?
  218.         ENABLE NEW OPEN ABOUT QUIT PREF#?
  219.  
  220.    SEE ALSO
  221.     ENABLE
  222.  
  223.    BUGS
  224.     Doesn't disable menu items yet.
  225.  
  226. appshell.library/__ENABLE                           appshell.library/__ENABLE
  227.  
  228.    NAME
  229.     ENABLE - Enable a function and its interfaces.
  230.  
  231.    SYNOPSIS
  232.     EnableID    Function ID
  233.  
  234.    FUNCTION
  235.     This function allows an application or user to enable a function.
  236.  
  237.     If the function is attached to a gadget or menu item, then that item
  238.     is also enabled.  This function does wildcard expansion.
  239.  
  240.     As a string command line:
  241.  
  242.         ENABLE
  243.         NAMES/M
  244.  
  245.         NAMES    The list of valid function names to enable.
  246.  
  247.     As a TagItem attribute list:
  248.  
  249.         APSH_NameTag, <name>
  250.         where <name> is a valid function name.
  251.  
  252.    SEE ALSO
  253.     DISABLE
  254.  
  255.    BUGS
  256.     Doesn't enable menu items yet.
  257.  
  258. appshell.library/__FAULT                             appshell.library/__FAULT
  259.  
  260.    NAME
  261.     FAULT - Return the text for an error number.
  262.  
  263.    SYNOPSIS
  264.     FaultID        Function ID
  265.  
  266.    FUNCTION
  267.     This function will return the text assigned to an error number.
  268.  
  269.     As a string command line:
  270.  
  271.         FAULT
  272.         /N
  273.  
  274.         /N    Number to return the text for.
  275.  
  276.     This function is implemented by the ARexx message handler.
  277.  
  278. appshell.library/__RX                                   appshell.library/__RX
  279.  
  280.    NAME
  281.     RX - Execute an ARexx macro.
  282.  
  283.    SYNOPSIS
  284.     RXID        Function ID
  285.  
  286.    FUNCTION
  287.     Allows access to ARexx functions that may have otherwise been
  288.     rerouted by the application.  Should only be used if there are name
  289.     conflicts between an application function and an ARexx function.
  290.  
  291.     As a string command line:
  292.  
  293.         RX
  294.         ASYNC/S, CMD/F
  295.  
  296.         ASYNC    Send the command to the asynchronous port.
  297.  
  298.         CMD    Command to execute.
  299.  
  300.     As a TagItem attribute list:
  301.  
  302.         APSH_CmdString, <command>
  303.         where <command> is a command line to pass to ARexx.
  304.  
  305.     This function is implemented by the ARexx message handler.
  306.  
  307.    BUGS
  308.     ASYNC is not implemented.
  309.  
  310. appshell.library/__RXS                                 appshell.library/__RXS
  311.  
  312.    NAME
  313.     RXS - Execute an ARexx string file.
  314.  
  315.    SYNOPSIS
  316.     RXSID        Function ID
  317.  
  318.    FUNCTION
  319.     Allows access to ARexx functions that may have otherwise been
  320.     rerouted by the application.  Should only be used if there are name
  321.     conflicts between an application function and an ARexx function.
  322.  
  323.     As a string command line:
  324.  
  325.         RXS
  326.         ASYNC/S, STRING/F
  327.  
  328.         ASYNC    Send the command to the asynchronous port.
  329.  
  330.         STRING    String file to execute.
  331.  
  332.     As a TagItem attribute list:
  333.  
  334.         APSH_CmdString, <command>
  335.         where <command> is a command line to pass to ARexx.
  336.  
  337.     This function is implemented by the ARexx message handler.
  338.  
  339.    BUGS
  340.     ASYNC is not implemented.
  341.  
  342. appshell.library/__STUB                               appshell.library/__STUB
  343.  
  344.    NAME
  345.     STUB - A do nothing function.
  346.  
  347.    SYNOPSIS
  348.     StubID        Function ID
  349.  
  350.    FUNCTION
  351.     This function does absolutely nothing.
  352.  
  353.     As a string command line:
  354.  
  355.         STUB
  356.  
  357. appshell.library/__SYSTEM                           appshell.library/__SYSTEM
  358.  
  359.    NAME
  360.     SYSTEM - Execute a system command or application.
  361.  
  362.    SYNOPSIS
  363.     SystemID    Function ID
  364.  
  365.    FUNCTION
  366.     This function uses the AmigaDOS command Run to execute a command.
  367.  
  368.     As a string command line:
  369.  
  370.         SYSTEM
  371.         ASYNC/S,PUBSCREEN/S,HOSTPORT/S,COMMAND/F
  372.  
  373.         ASYNC        Run the command asynchronously.
  374.  
  375.         PUBSCREEN    Pass the name of the applications public
  376.                 screen with the PUBSCREEN keyword.
  377.  
  378.         HOSTPORT    Pass the name of the applications ARexx
  379.                 port with the HOSTPORT keyword.
  380.  
  381.     This function is implemented by the DOS message handler.
  382.  
  383. appshell.library/__WHY                                 appshell.library/__WHY
  384.  
  385.    NAME
  386.     WHY - Return information on the last error.
  387.  
  388.    SYNOPSIS
  389.     WhyID        Function ID
  390.  
  391.    FUNCTION
  392.     For scripting purpose, the primary return value of a command should
  393.     return an error level.  This limits the error return values to small
  394.     ranges (to be consistent with DOS).  Therefore, if commands use the
  395.     secondary return field to contain information on the actual error,
  396.     then this function will allow scripts to obtain information on what
  397.     the last error actually was.
  398.  
  399.     This command takes no parameters.
  400.  
  401.     This function is implemented by the ARexx message handler.
  402.  
  403. appshell.library/__WINDOW                           appshell.library/__WINDOW
  404.  
  405.    NAME
  406.     WINDOW - Open/Close an AppShell window
  407.  
  408.    SYNOPSIS
  409.     WindowID    Function ID
  410.  
  411.    FUNCTION
  412.     Provides a mechanism to open or close an AppShell window.
  413.  
  414.     As a string command line:
  415.  
  416.         WINDOW
  417.         NAME,TITLE/k,OPEN/s,CLOSE/s,SNAPSHOT/s,ACTIVATE/s,MIN/s,MAX/s,
  418.         FRONT/s,BACK/s,ZOOM/s,UNZOOM/s,LOCK/s,UNLOCK/s
  419.  
  420.         NAME        Name of the window to manipulate.
  421.         TITLE        Title to assign to the window.
  422.         OPEN        Open the window.
  423.         CLOSE        Close the window.
  424.         SNAPSHOT    Save the window information to disk.
  425.         ACTIVATE    Activate the window.
  426.         MIN        Set the window to minimum size.
  427.         MAX        Set the window to maximum size.
  428.         FRONT        Send the window to the front.
  429.         BACK        Send the window to the back.
  430.         ZOOM        Set the window to its zoom size.
  431.         UNZOOM        Set the window to its normal size.
  432.         LOCK        Lock out input to the window.
  433.         UNLOCK        Unlock a locked window.
  434.  
  435.     As a TagItem attribute list:
  436.  
  437.         APSH_NameTag, <name>
  438.         where <name> is a valid window name.
  439.  
  440.         APSH_WinPointer, <pointer>
  441.         where <pointer> points to a valid window structure.
  442.  
  443.         APSH_Command, <cmd>
  444.         where <cmd> is a valid command.
  445.             APSH_MH_OPEN    To open the window.
  446.             APSH_MH_CLOSE    To close the window.
  447.  
  448.     This function is implemented by the IDCMP message handler.
  449.  
  450.    SEE ALSO
  451.     WINDOWTOBACK, WINDOWTOFRONT
  452.  
  453. appshell.library/__WINDOWTOBACK               appshell.library/__WINDOWTOBACK
  454.  
  455.    NAME
  456.     WINDOWTOBACK - Send an AppShell window to the back.
  457.  
  458.    SYNOPSIS
  459.     WindowToBackID    Function ID
  460.  
  461.    FUNCTION
  462.     Provides a mechanism to send an AppShell window to the back of the
  463.     other windows on the same screen.
  464.  
  465.     As a string command line:
  466.  
  467.         WINDOWTOBACK
  468.         NAME
  469.  
  470.         NAME    Name of the window to send to the back.  Defaults
  471.             to MAIN.
  472.  
  473.     As a TagItem attribute list:
  474.  
  475.         APSH_NameTag, <name>
  476.         where <name> is a valid window name.
  477.  
  478.         APSH_WinPointer, <pointer>
  479.         where <pointer> points to a valid window structure.
  480.  
  481.     This function is implemented by the IDCMP message handler.
  482.  
  483.    SEE ALSO
  484.     WINDOWTOFRONT, WINDOW
  485.  
  486. appshell.library/__WINDOWTOFRONT             appshell.library/__WINDOWTOFRONT
  487.  
  488.    NAME
  489.     WINDOWTOFRONT - Bring an AppShell window to the front.
  490.  
  491.    SYNOPSIS
  492.     WindowToFrontID    Function ID
  493.  
  494.    FUNCTION
  495.     Provides a mechanism to bring an AppShell window in front of the
  496.     other windows on the same screen.
  497.  
  498.     As a string command line:
  499.  
  500.         WINDOWTOFRONT
  501.         NAME
  502.  
  503.         NAME    Name of the window to bring to the front.  Defaults
  504.             to MAIN.
  505.  
  506.     As a TagItem attribute list:
  507.  
  508.         APSH_NameTag, <name>
  509.         where <name> is a valid window name.
  510.  
  511.         APSH_WinPointer, <pointer>
  512.         where <pointer> points to a valid window structure.
  513.  
  514.     This function is implemented by the IDCMP message handler.
  515.  
  516.    SEE ALSO
  517.     WINDOWTOBACK, WINDOW
  518.  
  519. appshell.library/AddFuncEntries               appshell.library/AddFuncEntries
  520.  
  521.    NAME
  522.     AddFuncEntries - Add an array of entries to the function table.
  523.  
  524.    SYNOPSIS
  525.     results = AddFuncEntries (ai, entries)
  526.     D0              D0  D1
  527.  
  528.     BOOL results;
  529.     struct AppInfo *ai;
  530.     struct Funcs *entries;
  531.  
  532.    FUNCTION
  533.     This function is used to add a NULL terminated array of entries to
  534.     the application's function table.
  535.  
  536.     The function table is maintained as an Exec linked list.  The AppShell
  537.     will free all entries when the application is shutdown.
  538.  
  539.    INPUTS
  540.     ai    - Pointer to the application's AppInfo structure.
  541.     entries    - Pointer to a NULL terminated array of Funcs structures that
  542.           describes the entry to be added to the function table.
  543.  
  544.    RESULT
  545.     TRUE    - AppShell was able to add the array to the table.
  546.     FALSE    - Unable to add the array to the function table.
  547.  
  548.    SEE ALSO
  549.     AddFuncEntry(), FreeFuncEntry(), FreeFuncEntries()
  550.  
  551. appshell.library/AddFuncEntry                   appshell.library/AddFuncEntry
  552.  
  553.    NAME
  554.     AddFuncEntry - Add an entry to the function table
  555.  
  556.    SYNOPSIS
  557.     results = AddFuncEntry (ai, entry)
  558.     D0            D0  D1
  559.  
  560.     BOOL results;
  561.     struct AppInfo *ai;
  562.     struct Funcs *entry;
  563.  
  564.    FUNCTION
  565.     This function is used to add a new entry to the application's
  566.     function table.
  567.  
  568.     The function table is maintained as an Exec linked list.  The
  569.     AppShell will free all entries when the application is shutdown.
  570.  
  571.    INPUTS
  572.     ai    - Pointer to the application's AppInfo structure.
  573.     entry    - Pointer to a Funcs structure that describes the entry
  574.           to be added to the function table.
  575.  
  576.    RESULT
  577.     TRUE    - AppShell was able to add the function to the table.
  578.     FALSE    - Unable to add the entry to the function table.
  579.  
  580.    SEE ALSO
  581.     AddFuncEntries(), FreeFuncEntry(), FreeFuncEntries()
  582.  
  583. appshell.library/AddProjects                     appshell.library/AddProjects
  584.  
  585.     NAME
  586.     AddProjects - Add an array of WBArgs to the project list.
  587.  
  588.     SYNOPSIS
  589.     result = AddProjects (ai, numargs, args, attrs)
  590.     D0              D0  D1       A0    A1
  591.  
  592.     BOOL result;
  593.     struct AppInfo *ai;
  594.     LONG numargs;
  595.     struct WBArg *args;
  596.     struct TagItem *attrs;
  597.  
  598.     FUNCTION
  599.     Add an array of WBArgs to the given project list.  Defaults to the
  600.     main project list.
  601.  
  602.     Valid TagItems are:
  603.  
  604.         APSH_ProjInfo,<project>
  605.         Where <project> is a valid pointer to a Project structure.
  606.         Defaults to the AppInfo project structure.
  607.  
  608.     INPUTS
  609.     ai    - Pointer to the application AppInfo structure.
  610.     numargs    - Number of arguments in the array.
  611.     args    - Pointer to an array of WBArg structures.
  612.     attrs    - Pointer to an optional TagItem array.
  613.  
  614. appshell.library/APSHClearPointer           appshell.library/APSHClearPointer
  615.  
  616.    NAME
  617.     APSHClearPointer - Restore the default pointer.
  618.  
  619.    SYNOPSIS
  620.     APSHClearPointer (ai, attrs)
  621.               D0  D1
  622.  
  623.     struct AppInfo * ai;
  624.     struct TagItem * attrs;
  625.  
  626.    FUNCTION
  627.     This function restores the default pointer for the specified window.
  628.     Defaults to the current window (according to AppShell).  The image
  629.     comes from ENV:<basename>/pointer.ilbm
  630.  
  631.     Valid TagItems are:
  632.  
  633.         APSH_WinName, <name>
  634.         where <name> is a valid window name.
  635.  
  636.         APSH_WinPointer, <pointer>
  637.         where <pointer> points to a valid window.
  638.  
  639.    INPUTS
  640.     ai    - Optional pointer to the AppInfo structure for this
  641.           application.
  642.     attrs    - Optional pointer to an array of TagItems.
  643.  
  644.    SEE ALSO
  645.     APSHSetWaitPointer
  646.  
  647. appshell.library/APSHGetGadgetInfo         appshell.library/APSHGetGadgetInfo
  648.  
  649.    NAME
  650.     APSHGetGadgetInfo - Obtain a pointer to a gadget and its window.
  651.  
  652.    SYNOPSIS
  653.     success = APSHGetGadgetInfo (ai, winname, gadname, winptr, gadptr)
  654.  
  655.     BOOL success;
  656.     struct AppInfo *ai;
  657.     STRPTR winname, gadname;
  658.     ULONG *winptr, *gadptr;
  659.  
  660.    FUNCTION
  661.     Obtain a pointer to a gadget and the window that it belongs in.
  662.  
  663.     Always use this function to get a pointer to a gadget before
  664.     manipulating it.  Never store the gadget or window pointers in your
  665.     UserData for the application.  It is possible that the window is
  666.     closed or been closed since the time you last obtained a gadget
  667.     pointer and are therefore referencing invalid memory locations.
  668.  
  669.     This function is implemented by the IDCMP message handler.
  670.  
  671.    EXAMPLE
  672.  
  673.     /* Sample function showing how to use APSHGetGadgetInfo */
  674.     VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl)
  675.     {
  676.         struct Gadget *gad;
  677.         struct Window *win;
  678.  
  679.         /* Get a pointer to the main window, named MAIN, and the Scrolling
  680.          * List gadget, which is named LIST.
  681.          */
  682.         if (APSHGetGadgetInfo (ai, "MAIN", "LIST",
  683.                    (ULONG *)&win, (ULONG *)&gad))
  684.         {
  685.         /* ... do something with the fields ... */
  686.         }
  687.     }
  688.  
  689.  
  690.    INPUTS
  691.     ai    - Pointer to the AppInfo structure
  692.     winname    - Pointer to the name of the window that the gadget is
  693.           supposed to be located in.
  694.     gadname    - Pointer to the name of the gadget.
  695.     winptr    - Address of the variable to place the window pointer in.
  696.     gadptr    - Address of the variable to place the gadget pointer in.
  697.  
  698.    RETURN
  699.     success    - TRUE indicates that the system was able to locate
  700.           the gadget and that gadptr is set.  winptr can be
  701.           used to determine if the window is actually open.
  702.  
  703.           FALSE indicates that the system was unable to locate
  704.           the gadget.
  705.  
  706.    BUGS
  707.     This version of the AppShell has stolen the window and gadget
  708.     UserData fields.  Until a method is provided to access per window
  709.     and gadget data, don't use the window->UserData or gadget->UserData.
  710.  
  711. appshell.library/APSHGetWindowInfo         appshell.library/APSHGetWindowInfo
  712.  
  713.    NAME
  714.     APSHGetWindowInfo - Obtain a pointer to a window.
  715.  
  716.    SYNOPSIS
  717.     success = APSHGetWindowInfo (ai, winname, winptr)
  718.  
  719.     BOOL success;
  720.     struct AppInfo *ai;
  721.     STRPTR winname;
  722.     ULONG *winptr;
  723.  
  724.    FUNCTION
  725.     Obtain a pointer to the named window.
  726.  
  727.     Always use this function to get a pointer to a window before
  728.     manipulating it.  Never store the window pointers in the application's
  729.     UserData.  It is possible that the window is closed or been closed
  730.     since the time you last obtained its pointer and are therefore
  731.     referencing invalid memory locations.
  732.  
  733.     This function is implemented by the IDCMP message handler.
  734.  
  735.    EXAMPLE
  736.  
  737.     /* Sample function showing how to use APSHGetWindowInfo */
  738.     VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl)
  739.     {
  740.         struct Window *win;
  741.  
  742.         /* Get a pointer to the main window, named MAIN */
  743.         if (APSHGetWindowInfo (ai, "MAIN", (ULONG)&win))
  744.         {
  745.         /* ... do something with the fields ... */
  746.         }
  747.     }
  748.  
  749.  
  750.    INPUTS
  751.     ai    - Pointer to the AppInfo structure
  752.     winname    - Pointer to the name of the window.
  753.     winptr    - Address of the variable to place the window pointer in.
  754.  
  755.    RETURN
  756.     success    - TRUE indicates that the system was able to locate
  757.           the named window and that it was open.
  758.  
  759.           FALSE indicates that the system was unable to locate
  760.           the named window or that it wasn't open.
  761.  
  762.    BUGS
  763.     This version of the AppShell has stolen the window and gadget
  764.     UserData fields.  Until a method is provided to access per window
  765.     and gadget data, don't use the window->UserData or gadget->UserData.
  766.  
  767. appshell.library/APSHSetWaitPointer       appshell.library/APSHSetWaitPointer
  768.  
  769.    NAME
  770.     APSHSetWaitPointer - Display a wait pointer.
  771.  
  772.    SYNOPSIS
  773.     APSHSetWaitPointer (ai, attrs)
  774.                 D0  D1
  775.  
  776.     struct AppInfo * ai;
  777.     struct TagItem * attrs;
  778.  
  779.    FUNCTION
  780.     This function displays a wait pointer in the specified window.
  781.     Defaults to the current window (according to AppShell).  The image
  782.     comes from ENV:<basename>/busypointer.ilbm
  783.  
  784.     Valid TagItems are:
  785.  
  786.         APSH_WinName, <name>
  787.         where <name> is a valid window name.
  788.  
  789.         APSH_WinPointer, <pointer>
  790.         where <pointer> points to a valid window.
  791.  
  792.    EXAMPLE
  793.  
  794.     struct TagItem attr[2];
  795.  
  796.     /* Set the wait pointer */
  797.     attr[0].ti_Tag = APSH_WinName;
  798.     attr[0].ti_Data = (ULONG) "Main";
  799.     attr[1].ti_Tag = TAG_DONE;
  800.     APSHSetWaitPointer (ai, attr);
  801.  
  802.     /* Bring up the ASL file requester */
  803.     if (AslRequest (ad->ad_FR, SaveTags))
  804.     {
  805.         /* Build up the complete project file name */
  806.         strcpy (ad->ad_Name, ad->ad_FR->rf_Dir);
  807.         AddPart (ad->ad_Name, ad->ad_FR->rf_File, 256);
  808.  
  809.         /* Save the file */
  810.     }
  811.  
  812.     /* Clear the wait pointer */
  813.     APSHClearPointer (ai, attr);
  814.  
  815.    INPUTS
  816.     ai    - Optional pointer to the AppInfo structure for this
  817.           application.
  818.     attrs    - Optional pointer to an array of TagItems.
  819.  
  820.    SEE ALSO
  821.     APSHClearPointer
  822.  
  823. appshell.library/BuildParseLine               appshell.library/BuildParseLine
  824.  
  825.    NAME
  826.     BuildParseLine - Non-destructive string parser
  827.  
  828.    SYNOPSIS
  829.     handle = BuildParseLine (line, argc, argv)
  830.     D0             D0    D1    A0
  831.  
  832.     STRPTR handle;
  833.     STRPTR line;
  834.     ULONG *argc;
  835.     STRPTR argv[MAXARGS];
  836.  
  837.    FUNCTION
  838.     This function is used to parse a string that may end up being
  839.     passed to another function.  It does not modify the passed
  840.     string.  Requires a corresponding call to FreeParseLine, when the
  841.     application's function is done with the parsed line.
  842.  
  843.    INPUTS
  844.     line     - Pointer to the string to parse.
  845.     argc     - Pointer to variable to hold the number of arguments.
  846.     argv     - Pointer to an array to hold the arguments.  The array
  847.            must contain MAXARGS entries.
  848.  
  849.    RETURN
  850.     handle   - Pointer to a temporary work area which must be passed
  851.            back to FreeParseLine when done with the parsed array.
  852.  
  853.    EXAMPLE
  854.  
  855.     /* sample function showing how to use BuildParseLine & FreeParseLine */
  856.     function()
  857.     {
  858.         STRPTR argv[MAXARGS], handle = NULL;
  859.         ULONG argc;
  860.  
  861.         /* Parse the command line */
  862.         handle = BuildParseLine ("ACTIVATE ME", &argc, argv);
  863.  
  864.         /* Do something with the parsed command line.  The strings
  865.          * must be copied before calling FreeParseLine if they are
  866.          * going to be used later.
  867.          */
  868.         printf("%ld words, first is %s\n", argc, argv[0]);
  869.  
  870.         /* free the BuildParseLine resources */
  871.         FreeParseLine(handle);
  872.     }
  873.  
  874.    SEE ALSO
  875.     FreeParseLine(), ParseLine()
  876.  
  877. appshell.library/ExpandPattern                 appshell.library/ExpandPattern
  878.  
  879.     NAME
  880.     ExpandPattern - Expand pattern into files.
  881.  
  882.     SYNOPSIS
  883.     success = ExpandPattern (ai, cmd, attrs)
  884.     D0             A1  A2   A3
  885.  
  886.     struct AppInfo *ai;
  887.     STRPTR cmd;
  888.     struct TagItem *attrs;
  889.  
  890.     FUNCTION
  891.     Expands a pattern into a list of file names, the names are added
  892.     to a project list.
  893.  
  894.     Valid TagItems are:
  895.  
  896.         APSH_ArgList, <list>
  897.         NULL terminated argument list, as returned by ReadArgs for a
  898.         /M argument.
  899.  
  900.     INPUTS
  901.     ai    - Pointer to the application AppInfo structure.
  902.     cmd    - Pointer to an optional command string.
  903.     attrs    - Pointer to the TagItem array.
  904.  
  905.     RESULT
  906.     success    - TRUE to indicate success, FALSE for failure.
  907.  
  908. appshell.library/FindType                           appshell.library/FindType
  909.  
  910.    NAME
  911.     FindType - Find the value of a variable.
  912.  
  913.    SYNOPSIS
  914.     value = FindType(argv, name, defvalue)
  915.     D0         D0    D1    A0
  916.  
  917.     STRPTR value;
  918.     STRPTR argv[MAXARGS];
  919.     STRPTR name, defvalue;
  920.  
  921.    FUNCTION
  922.     This function searches a parsed text array for a given entry and
  923.     returns a pointer to the value bound to that entry.  If the entry is
  924.     not found, then a pointer to defvalue is returned.
  925.  
  926.    EXAMPLE
  927.  
  928.     /* sample fragment showing how to use FindType */
  929.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  930.     {
  931.         STRPTR name;
  932.         STRPTR argv[MAXARG], clone=NULL;
  933.         ULONG argc;
  934.  
  935.         /* make sure we have a command line */
  936.         if (cmd)
  937.         {
  938.         /* parse the command line */
  939.         clone = BuildParseLine (cmd, &argc, argv);
  940.  
  941.         /* Get the file name.  If there isn't a FILE keyword, then
  942.          * use "config".  If the return value is to be used outside
  943.          * of this function, then it must be copied.
  944.          */
  945.         name = FindType (argv, "FILE", "config");
  946.         }
  947.  
  948.         /* free the BuildParseLine */
  949.         FreeParseLine (clone);
  950.     }
  951.  
  952.    INPUTS
  953.     argv     - Pointer to the preparsed text array.
  954.     name     - Entry to search for.
  955.     defvalue - Value to return if name isn't found.
  956.  
  957.    RESULTS
  958.     value     - A pointer to the string that is the value bound to name or
  959.            defvalue if name isn't found.
  960.  
  961.    SEE ALSO
  962.     MatchValue(), BuildParseLine(), FreeParseLine(), ParseLine(),
  963.     icon.library/FindToolType
  964.  
  965. appshell.library/FreeFuncEntries             appshell.library/FreeFuncEntries
  966.  
  967.    NAME
  968.     FreeFuncEntries - Free an application's function table.
  969.  
  970.    SYNOPSIS
  971.     FreeFuncEntries (ai)
  972.              D0
  973.  
  974.     struct AppInfo *ai;
  975.  
  976.    FUNCTION
  977.     This function is used to free an application's entire function
  978.     table.
  979.  
  980.    INPUTS
  981.     ai    - Pointer to the application's AppInfo structure.
  982.  
  983.    SEE ALSO
  984.     AddFuncEntry(), AddFuncEntries(), FreeFuncEntries()
  985.  
  986. appshell.library/FreeFuncEntry                 appshell.library/FreeFuncEntry
  987.  
  988.    NAME
  989.     FreeFuncEntry - Free an entry from the function table
  990.  
  991.    SYNOPSIS
  992.     FreeFuncEntry (ai, f_entry);
  993.                D0  D1
  994.  
  995.     struct AppInfo *ai;
  996.     struct FuncEntry *f_entry;
  997.  
  998.    FUNCTION
  999.     This function is used to free an entry from the application's
  1000.     function table.
  1001.  
  1002.    INPUTS
  1003.     ai    - Pointer to the application's AppInfo structure.
  1004.  
  1005.     f_entry    - Pointer to a FuncEntry structure that describes the
  1006.           entry to be added to the function table.
  1007.  
  1008.    SEE ALSO
  1009.     AddFuncEntry(), AddFuncEntries(), FreeFuncEntries()
  1010.  
  1011. appshell.library/FreeParseLine                 appshell.library/FreeParseLine
  1012.  
  1013.    NAME
  1014.     FreeParseLine - Free the BuildParseLine temporary work area
  1015.  
  1016.    SYNOPSIS
  1017.     FreeParseLine(handle)
  1018.               D0
  1019.  
  1020.     STRPTR handle;
  1021.  
  1022.    FUNCTION
  1023.     Free the temporary work space used by BuildParseLine.  A NULL is a
  1024.     valid argument.
  1025.  
  1026.    INPUTS
  1027.     handle   - Pointer to the return value from BuildParseLine.
  1028.  
  1029.    SEE ALSO
  1030.     BuildParseLine(), ParseLine()
  1031.  
  1032. appshell.library/FreeProject                     appshell.library/FreeProject
  1033.  
  1034.     NAME
  1035.     FreeProject - Removes and deallocate a project from the project list.
  1036.  
  1037.     SYNOPSIS
  1038.     FreeProject ( proj )
  1039.               D0
  1040.  
  1041.     struct ProjNode *proj;
  1042.  
  1043.     FUNCTION
  1044.     Removes and deallocates a project node from the project list.
  1045.  
  1046.     INPUTS
  1047.     proj    - Pointer to a valid ProjNode structure.
  1048.  
  1049. appshell.library/FreeProjects                   appshell.library/FreeProjects
  1050.  
  1051.     NAME
  1052.     FreeProjects - Remove and deallocate all the projects in a project list.
  1053.  
  1054.     SYNOPSIS
  1055.     FreeProjects (ai, attrs)
  1056.               D0  D1
  1057.  
  1058.     struct AppInfo *ai;
  1059.     struct TagItem *attrs;
  1060.  
  1061.     FUNCTION
  1062.     Removes and deallocate all the projects in a project list.  Defaults
  1063.     to the main project list.
  1064.  
  1065.     Valid TagItems are:
  1066.  
  1067.         APSH_ProjInfo,<project>
  1068.         Where <project> is a valid pointer to a Project structure.
  1069.         Defaults to the AppInfo project structure.
  1070.  
  1071.     INPUTS
  1072.     ai    - Pointer to the application AppInfo structure.
  1073.     attrs    - Pointer to an optional TagItem array.
  1074.  
  1075. appshell.library/GetFuncEntry                   appshell.library/GetFuncEntry
  1076.  
  1077.    NAME
  1078.     GetFuncEntry - Get a pointer to a function table entry.
  1079.  
  1080.    SYNOPSIS
  1081.     entry = GetFuncEntry (ai, cmd, fid)
  1082.     D0              D0  D1   A0
  1083.  
  1084.     struct FuncEntry *entry;
  1085.     struct AppInfo *ai;
  1086.     STRPTR cmd;
  1087.     ULONG fid;
  1088.  
  1089.    FUNCTION
  1090.     This function is used to obtain a pointer to a function table entry.
  1091.  
  1092.     Currently the FuncEntry structure is private.
  1093.  
  1094.    INPUTS
  1095.     ai    - Pointer to the application's AppInfo structure.
  1096.     cmd    - Pointer to the command name to locate.  Either cmd or fid
  1097.           must be provided.
  1098.     fid    - Command ID of the command to locate.
  1099.  
  1100.    RESULT
  1101.     entry    - Pointer to a FuncEntry structure that describes the command.
  1102.  
  1103.    SEE ALSO
  1104.     GetFuncID(), GetFuncName()
  1105.  
  1106. appshell.library/GetFuncID                         appshell.library/GetFuncID
  1107.  
  1108.    NAME
  1109.     GetFuncID - Given a command name, return the ID for the function.
  1110.  
  1111.    SYNOPSIS
  1112.     fid = GetFuncID (ai, cmd)
  1113.     D0         D0  D1
  1114.  
  1115.     ULONG fid;
  1116.     struct AppInfo *ai;
  1117.     STRPTR cmd;
  1118.  
  1119.    FUNCTION
  1120.     This function will return the command ID for the function.
  1121.  
  1122.    INPUTS
  1123.     ai    - Pointer to the application's AppInfo structure.
  1124.     cmd    - Pointer to the command name to locate.
  1125.  
  1126.    RESULT
  1127.     fid    - Command ID of the function.
  1128.  
  1129.    SEE ALSO
  1130.     GetFuncEntry(), GetFuncName()
  1131.  
  1132. appshell.library/GetFuncName                     appshell.library/GetFuncName
  1133.  
  1134.    NAME
  1135.     GetFuncName - Given a command ID, return the name of the function.
  1136.  
  1137.    SYNOPSIS
  1138.     cmd = GetFuncName (ai, fid)
  1139.     D0           D0  D1
  1140.  
  1141.     STRPTR cmd;
  1142.     struct AppInfo *ai;
  1143.     ULONG fid;
  1144.  
  1145.    FUNCTION
  1146.     This function will return the name of the function for the given
  1147.     command ID.
  1148.  
  1149.    INPUTS
  1150.     ai    - Pointer to the application's AppInfo structure.
  1151.     fid    - Command ID of the function.
  1152.  
  1153.    RESULT
  1154.     cmd    - Pointer to the command name.
  1155.  
  1156.    SEE ALSO
  1157.     GetFuncEntry(), GetFuncID()
  1158.  
  1159. appshell.library/GetProjNode                     appshell.library/GetProjNode
  1160.  
  1161.     NAME
  1162.     GetProjNode - Get the requested project node.
  1163.  
  1164.     SYNOPSIS
  1165.     proj = GetProjNode (ai, id, attrs)
  1166.     D0            D0  D1  A0
  1167.  
  1168.     struct ProjNode *proj;
  1169.     struct AppInfo *ai;
  1170.     LONG id;
  1171.     struct TagItem *attrs;
  1172.  
  1173.     FUNCTION
  1174.     Given a project ID, find the correct ProjNode.
  1175.  
  1176.     Valid TagItems are:
  1177.  
  1178.         APSH_ProjInfo,<project>
  1179.         Where <project> is a valid pointer to a Project structure.
  1180.         Defaults to the AppInfo project structure.
  1181.  
  1182.     INPUTS
  1183.     ai    - Pointer to the application AppInfo structure.
  1184.     id    - Project ID to locate.
  1185.     attrs    - Pointer to an optional TagItem array.
  1186.  
  1187. appshell.library/GetText                             appshell.library/GetText
  1188.  
  1189.    NAME
  1190.     GetText - Obtain a pointer to a permanent read-only text message.
  1191.  
  1192.    SYNOPSIS
  1193.     text = GetText(ai, base, id, def)
  1194.     D0             D0  D1    A0  A1
  1195.  
  1196.     STRPTR text;
  1197.     struct AppInfo *ai;
  1198.     ULONG base, id;
  1199.     STRPTR def;
  1200.  
  1201.    FUNCTION
  1202.     Used to obtain a pointer to a permanent text message.  The text
  1203.     return value must not be modified.
  1204.  
  1205.     The main use for this function is for setting up text labels.
  1206.  
  1207.     NOTE: The text table can not have any NULL entries, except to
  1208.     mark the end of the table.  Due to the text table being exposed
  1209.     to the public (via the FAULT command), this function makes sure
  1210.     the number is within the valid range of the table.
  1211.  
  1212.    EXAMPLE
  1213.  
  1214.     /* sample function to show how to use GetText */
  1215.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1216.     {
  1217.         STRPTR label;
  1218.  
  1219.         /* get the current text to use for Okay */
  1220.         label = GetText (ai, APSH_MAIN_ID, APSH_OKAY_TXT, NULL);
  1221.     }
  1222.  
  1223.    INPUTS
  1224.     ai    - Pointer to the AppInfo structure for this application.
  1225.     base    - Text table to use.
  1226.  
  1227.           APSH_USER_ID for the application text table.
  1228.           APSH_MAIN_ID for the AppShell text table.
  1229.           or may provide a custom message handler base ID.
  1230.  
  1231.     id    - Text Table entry id.
  1232.     def    - Must be NULL.
  1233.  
  1234.    SEE ALSO
  1235.     PrepText()
  1236.  
  1237. appshell.library/HandleApp                         appshell.library/HandleApp
  1238.  
  1239.    NAME
  1240.     HandleApp - startup function for AppShell application
  1241.  
  1242.    SYNOPSIS
  1243.     results = HandleApp (argc, argv, wbm, attrs)
  1244.     D0             D0    D1    A0   A1
  1245.  
  1246.     BOOL results;
  1247.     int argc;
  1248.     char **argv;
  1249.     struct WBStartup *wbm;
  1250.     struct TagItem *attrs;
  1251.  
  1252.    FUNCTION
  1253.     This function is the application entry point to the AppShell.
  1254.  
  1255.    EXAMPLE
  1256.  
  1257.     /* ... application description tags ... */
  1258.  
  1259.     extern struct WBStartup *WBenchMsg;
  1260.  
  1261.     void main(int argc, char **argv)
  1262.     {
  1263.         HandleApp(argc, argv, WBenchMsg, tags);
  1264.     }
  1265.  
  1266.    INPUTS
  1267.     argc    - Number of Shell arguments being passed.
  1268.  
  1269.     argv    - Pointer to the Shell argument list
  1270.  
  1271.     wbm    - Pointer to the Workbench startup message.
  1272.  
  1273.     attrs    - Pointer to the application's user interface
  1274.           description.
  1275.  
  1276.    RESULT
  1277.     TRUE    - Application was able to initialize and run.
  1278.  
  1279.     FALSE    - Application failed.  AppShell has already informed
  1280.           user of what and where the failure was.
  1281.  
  1282.    SEE ALSO
  1283.     HandleAppAsync()
  1284.  
  1285. appshell.library/HandleAppAsync               appshell.library/HandleAppAsync
  1286.  
  1287.    NAME
  1288.     HandleAppAsync - startup function for an asynchronous AppShell
  1289.     application.
  1290.  
  1291.    SYNOPSIS
  1292.     results = HandleAppAsync (attrs, sipc)
  1293.     D0              D0     D1
  1294.  
  1295.     BOOL results;
  1296.     struct TagItem *attrs;
  1297.     struct MsgPort *sipc;
  1298.  
  1299.    FUNCTION
  1300.     This function is the application entry point for an asynchronous
  1301.     AppShell application.  This function should be called via the
  1302.     Tool Message Handler and allows an AppShell application to have
  1303.     multiple projects each with their own process.  Note that
  1304.     directly calling this function will not cause an asynchronous
  1305.     process to be launched.
  1306.  
  1307.    EXAMPLE
  1308.  
  1309.     /* This example shows how an application can clone itself to handle
  1310.      * multiple projects.
  1311.      *
  1312.      * APSH_Tool      the name to give to the cloned process.
  1313.      * APSH_ToolData  the user interface tag description.
  1314.      */
  1315.     VOID CloneFunc(struct AppInfo *ai, STRPTR args, struct TagItem *tl)
  1316.     {
  1317.         HandlerFunc (ai,
  1318.              APSH_Handler,   "TOOL",
  1319.              APSH_Command,   APSH_MH_OPEN,
  1320.              APSH_Tool,      "AppShell_Clone",
  1321.              APSH_ToolData,  Cloned_App,
  1322.              TAG_DONE);
  1323.     }
  1324.  
  1325.    INPUTS
  1326.     attrs    - Pointer to the application's user interface
  1327.           description.
  1328.  
  1329.     sipc    - SIPC message port by which the master application
  1330.           can control the cloned application.
  1331.  
  1332.    RESULT
  1333.     TRUE    - Application was able to initialize and run.
  1334.  
  1335.     FALSE    - Application failed.  AppShell has already informed
  1336.           user of what and where the failure was.
  1337.  
  1338.    SEE ALSO
  1339.     HandleApp()
  1340.  
  1341. appshell.library/HandlerDataA                   appshell.library/HandlerDataA
  1342.  
  1343.    NAME
  1344.     HandlerDataA - Obtain a pointer to a message handlers' instance data
  1345.  
  1346.    SYNOPSIS
  1347.     mh = HandlerDataA (ai, attrs)
  1348.     D0           D0  D1
  1349.  
  1350.     struct MsgHandler *mh;
  1351.     struct AppInfo *ai;
  1352.     struct TagItem *attrs;
  1353.  
  1354.    FUNCTION
  1355.     Used to obtain a pointer to a message handlers' instance data.
  1356.  
  1357.    EXAMPLE
  1358.  
  1359.     /* sample stub function to show how to obtain a message handlers'
  1360.      * data
  1361.      */
  1362.     VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1363.     {
  1364.         struct MsgHandler *mh;
  1365.  
  1366.         /* get a pointer to the message handler data */
  1367.         if (mh = HandlerData(ai,APSH_Handler,"MYH",TAG_DONE))
  1368.         {
  1369.         struct MHObject *mho = &(mh->mh_Header);
  1370.         struct myhInfo *md = mho->mho_SysData;
  1371.  
  1372.         /* do something with the data now... */
  1373.         }
  1374.     }
  1375.  
  1376.    INPUTS
  1377.     ai    - pointer to the AppInfo structure for this application.
  1378.     tags    - stack based TagItems.
  1379.  
  1380.    RESULTS
  1381.     mh    - Pointer to a MsgHandler structure.
  1382.  
  1383.    SEE ALSO
  1384.     HandlerFuncA()
  1385.  
  1386. appshell.library/HandlerFuncA                   appshell.library/HandlerFuncA
  1387.  
  1388.    NAME
  1389.     HandlerFuncA - entry point for a low-level message handler function.
  1390.  
  1391.    SYNOPSIS
  1392.     success = HandlerFuncA (ai, attrs)
  1393.     D0            D0  D1
  1394.  
  1395.     BOOL success;
  1396.     struct AppInfo *ai;
  1397.     struct TagItem *attrs;
  1398.  
  1399.    FUNCTION
  1400.     Provides an entry point for the low-level message handler functions.
  1401.  
  1402.    EXAMPLE
  1403.  
  1404.     /* sample stub function to show how to call a low-level message
  1405.      * handler function.
  1406.      *
  1407.      * This example tells the IDCMP message handler to open the window
  1408.      * (and it's environment) named MAIN.
  1409.      */
  1410.     VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1411.     {
  1412.         HandlerFunc(ai,
  1413.             APSH_Handler, "IDCMP",
  1414.             APSH_Command, APSH_MH_OPEN,
  1415.             APSH_NameTag, "MAIN",
  1416.             TAG_DONE);
  1417.     }
  1418.  
  1419.    INPUTS
  1420.     ai    - pointer to the AppInfo structure for this application.
  1421.     tags    - stack based TagItems.
  1422.  
  1423.    SEE ALSO
  1424.     HandlerDataA()
  1425.  
  1426. appshell.library/IconFromWBArg                 appshell.library/IconFromWBArg
  1427.  
  1428.    NAME
  1429.     IconFromWBArg - Obtains the icon from a Workbench argument.
  1430.  
  1431.    SYNOPSIS
  1432.     dob = IconFromWBArg (wbarg)
  1433.     D0             D0
  1434.  
  1435.     struct DiskObject *dob;
  1436.     struct WBArg *wbarg;
  1437.  
  1438.    FUNCTION
  1439.     Given a valid Workbench argument, this command will return the
  1440.     proper icon.  This call uses the new (V36) GetDiskObjectNew call
  1441.     to ensure that an icon will be returned.
  1442.  
  1443.    INPUTS
  1444.     wbarg    - Pointer to a filled in WBArg structure.
  1445.  
  1446.    RESULTS
  1447.     dob    - Pointer to a DiskObject structure.  Application must call
  1448.           FreeDiskObject when done with the icon.
  1449.  
  1450. appshell.library/LMatchFirst                     appshell.library/LMatchFirst
  1451.  
  1452.    NAME
  1453.     LMatchFirst - Finds node that matches pattern.
  1454.  
  1455.    SYNOPSIS
  1456.     error = LMatchFirst(list, pat, anchor);
  1457.     D0            D0    D1   D2
  1458.  
  1459.    FUNCTION
  1460.     Locates the first node that matches a given pattern.  This function
  1461.     is the same as the corresponding DOS function MatchFirst except
  1462.     that this function operates on an Exec list instead of the file
  1463.     system.
  1464.  
  1465.     This set of functions is case insensitive.  Set the
  1466.     APSHF_ANCHOR_NOCASE flag in the al_Flags field to get a caseless
  1467.     comparision.
  1468.  
  1469.    INPUTS
  1470.     list    - List to search through.
  1471.     pat    - Pattern to search for.
  1472.     anchor    - Bookmark for the search.
  1473.  
  1474.    EXAMPLES
  1475.  
  1476.     /* sample function showing how to step through a list of
  1477.      * of arguments and expand wildcards, if any */
  1478.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1479.     {
  1480.         struct AppData *ad = ai->ai_UserData;
  1481.         struct List *list = &(ad->ad_MyList);
  1482.         struct AnchorList al = {NULL};
  1483.         LONG retval = RETURN_ERROR;
  1484.         STRPTR *sptr = NULL, name;
  1485.         struct Funcs *fe;
  1486.  
  1487.         /* make sure that we have a tag list */
  1488.         if (tl)
  1489.         {
  1490.         /* get a pointer to the function entry */
  1491.         if (fe = (struct Funcs *)GetTagData(APSH_FuncEntry, NULL, tl))
  1492.         {
  1493.             /* our first argument is a MultiArg */
  1494.             sptr = (STRPTR *) fe->fe_Options[0];
  1495.         }
  1496.         }
  1497.  
  1498.         /* make sure we have an argument array to step thru */
  1499.         if (sptr)
  1500.         {
  1501.         /* step thru the argument array */
  1502.         while (*sptr)
  1503.         {
  1504.             for (retval = LMatchFirst (list, *sptr, &al);
  1505.              retval == 0L;
  1506.              retval = LMatchNext (&al))
  1507.             {
  1508.             /* get the current node name */
  1509.             name = al.al_CurNode.ln_Name;
  1510.  
  1511.             /* do something with the name/node */
  1512.             printf ("%s\n", name);
  1513.             }
  1514.  
  1515.             /* end the pattern match */
  1516.             LMatchEnd (&al);
  1517.  
  1518.             /* next name/pattern */
  1519.             sptr++;
  1520.  
  1521.         } /* end of while arguments */
  1522.         } /* end of if arguments */
  1523.     }
  1524.  
  1525.    RESULT
  1526.     error    - 0 for success or error code from <dos/dos.h>
  1527.  
  1528.    SEE ALSO
  1529.     LMatchNext
  1530.     LMatchEnd
  1531.     dos/MatchFirst
  1532.     dos/MatchNext
  1533.     dos/MatchEnd
  1534.  
  1535. appshell.library/LockAppInfo                     appshell.library/LockAppInfo
  1536.  
  1537.    NAME
  1538.     LockAppInfo - Lock an application context for exclusive access.
  1539.  
  1540.    SYNOPSIS
  1541.     key = LockAppInfo ( ai );
  1542.     D0            A1
  1543.  
  1544.     LONG key;
  1545.     struct AppInfo *ai;
  1546.  
  1547.    FUNCTION
  1548.     This function locks an application context while the application
  1549.     manipulates the AppInfo structure.
  1550.  
  1551.    EXAMPLE
  1552.  
  1553.     LONG key;
  1554.  
  1555.     /* Lock the AppInfo structure for exclusive access */
  1556.     key = LockAppInfo (ai);
  1557.  
  1558.     /* Modify some part of the AppInfo structure */
  1559.  
  1560.     /* Unlock the AppInfo structure */
  1561.     UnlockAppInfo (key);
  1562.  
  1563.    INPUTS
  1564.     ai    - Pointer to a valid AppInfo structure.
  1565.  
  1566.    RETURNS
  1567.     key    - Key to be passed to UnlockAppInfo to unlock the
  1568.           application context.
  1569.  
  1570.    SEE ALSO
  1571.     UnlockAppInfo()
  1572.  
  1573. appshell.library/MatchValue                       appshell.library/MatchValue
  1574.  
  1575.    NAME
  1576.     MatchValue - Check a text argument for a particular flag.
  1577.  
  1578.    SYNOPSIS
  1579.     success = MatchValue(entry, value)
  1580.     D0             D0     D1
  1581.  
  1582.     BOOL success;
  1583.     STRPTR entry, value;
  1584.  
  1585.    FUNCTION
  1586.     This function searchs to see if a particular text flag is set in
  1587.     a text entry.
  1588.  
  1589.    EXAMPLE
  1590.  
  1591.     /* sample fragment showing how to use MatchValue */
  1592.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1593.     {
  1594.         STRPTR flagstr;
  1595.         ULONG flags = NULL;
  1596.         STRPTR argv[MAXARG], clone=NULL;
  1597.         ULONG argc;
  1598.  
  1599.         /* make sure we have a command line */
  1600.         if (cmd)
  1601.         {
  1602.         /* parse the command line */
  1603.         clone = BuildParseLine (cmd, &argc, argv);
  1604.  
  1605.         /* get the flag entry from the argument list */
  1606.         if (flagstr = FindType (argv, "FLAGS", NULL))
  1607.         {
  1608.             /* see if the CLOSE flag is present */
  1609.             if (MatchValue (flagstr, "CLOSE"))
  1610.             flags |= CLOSEWINDOW;
  1611.  
  1612.             /* see if the SIZE flag is present */
  1613.             if (MatchValue (flagstr, "SIZE"))
  1614.             flags |= NEWSIZE;
  1615.         }
  1616.         }
  1617.  
  1618.         /* free the BuildParseLine */
  1619.         FreeParseLine (clone);
  1620.     }
  1621.  
  1622.    INPUTS
  1623.     entry     - Entry to search in.
  1624.     value     - Value to search for.
  1625.  
  1626.    RESULTS
  1627.     value     - TRUE if the value was in the entry, otherwise returns
  1628.            FALSE.
  1629.  
  1630.    SEE ALSO
  1631.     FindType(), BuildParseLine(), FreeParseLine(), ParseLine(),
  1632.     icon.library/MatchToolValue
  1633.  
  1634. appshell.library/NewProject                       appshell.library/NewProject
  1635.  
  1636.     NAME
  1637.     NewProject - Create a project node and add it to the project list.
  1638.  
  1639.     SYNOPSIS
  1640.     proj = NewProject (ai, name, attrs)
  1641.     D0           D0  D1    A0
  1642.  
  1643.     struct ProjNode *proj;
  1644.     struct AppInfo *ai;
  1645.     STRPTR name;
  1646.     struct TagItem *attrs;
  1647.  
  1648.     FUNCTION
  1649.     Creates a project node of the given name and adds it to the requested
  1650.     project list.  The project list defaults to the main project list.
  1651.     If the name is NULL, the function will determine the name by finding
  1652.     the next available Unnamed slot.
  1653.  
  1654.     Valid TagItems are:
  1655.  
  1656.         APSH_ProjInfo, <project>
  1657.         Where <project> is a valid pointer to a Project structure.
  1658.         Defaults to the AppInfo project structure.
  1659.  
  1660.         APSH_NameTag, <name>
  1661.         Where <name> is the name to be added to the project list.
  1662.  
  1663.         APSH_TextID, <text ID>
  1664.         Where <text ID> is the text ID from the applications text
  1665.         table to use for the prefix when a name isn't given.  Defaults
  1666.         to Unnamed from the AppShell text table.  The resulting
  1667.         prefix will be truncated to twenty characters.
  1668.  
  1669.         APSH_BaseID, <base ID>
  1670.         Where <base ID> is the text table to use when APSH_TextID is
  1671.         supplied.  Defaults to APSH_USER_ID.
  1672.  
  1673.     INPUTS
  1674.     ai    - Pointer to the application AppInfo structure.
  1675.     name    - Pointer to the name to give to the project.
  1676.     attrs    - Pointer to an optional TagItem array.
  1677.  
  1678.     RESULT
  1679.     proj    - Pointer to a filled in ProjNode structure
  1680.  
  1681. appshell.library/NotifyUser                       appshell.library/NotifyUser
  1682.  
  1683.    NAME
  1684.     NotifyUser - Display a text message to the user.
  1685.  
  1686.    SYNOPSIS
  1687.     success = NotifyUser (ai, msg, attrs)
  1688.     D0              D0  D1   A0
  1689.  
  1690.     BOOL success;
  1691.     struct AppInfo * ai;
  1692.     STRPTR msg;
  1693.     struct TagItem * attrs;
  1694.  
  1695.    FUNCTION
  1696.     This function will display a text message to the user.  Currently
  1697.     uses EasyRequest (AutoRequest if OS version less than 2.0) to display
  1698.     messages.
  1699.  
  1700.    INPUTS
  1701.  
  1702.     ai    - Optional pointer to the AppInfo structure for this
  1703.           application.
  1704.  
  1705.     msg    - Pointer to message to display.  If this field is NULL, then
  1706.           the text will come from the ai->ai_TextRtn field.
  1707.  
  1708.     attrs    - Optional pointer to an array of TagItems.
  1709.  
  1710. appshell.library/ParseLine                         appshell.library/ParseLine
  1711.  
  1712.    NAME
  1713.     ParseLine - Destructive string parser
  1714.  
  1715.    SYNOPSIS
  1716.     argc = ParseLine (line, argv)
  1717.     D0          D0    D1
  1718.  
  1719.     ULONG argc;
  1720.     STRPTR line;
  1721.     STRPTR argv[MAXARGS];
  1722.  
  1723.    FUNCTION
  1724.     String parser.  Inserts '\0' after each word in the passed text
  1725.     line.
  1726.  
  1727.    INPUTS
  1728.     line     - Pointer to the string to parse.
  1729.     argv     - Pointer to an array to hold the arguments.  The array
  1730.            must contain MAXARGS entries.
  1731.  
  1732.    RETURN
  1733.     argc     - Number of arguments returned in argv
  1734.  
  1735.    EXAMPLE
  1736.  
  1737.     /* sample function showing how to use ParseLine */
  1738.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1739.     {
  1740.         UBYTE text[] = "ACTIVATE ME";
  1741.         STRPTR argv[MAXARGS];
  1742.         ULONG argc;
  1743.  
  1744.         /* parse the command line */
  1745.         argc = ParseLine (text, argv);
  1746.  
  1747.         /* simple display of some of the parse variables */
  1748.         printf("%ld words, first is %s\n", argc, argv[0]);
  1749.     }
  1750.  
  1751.    SEE ALSO
  1752.     BuildParseLine(), FreeParseLine()
  1753.  
  1754. appshell.library/PerfFunc                           appshell.library/PerfFunc
  1755.  
  1756.    NAME
  1757.     PerfFunc - The entry point to all commands in the function table.
  1758.  
  1759.    SYNOPSIS
  1760.     success = PerfFunc (ai, fid, cmdline, attrs)
  1761.     D0            D0  D1   A0       A1
  1762.  
  1763.     BOOL success;
  1764.     struct AppInfo *ai;
  1765.     ULONG fid;
  1766.     STRPTR cmdline;
  1767.     struct TagItem *attrs;
  1768.  
  1769.    FUNCTION
  1770.     This is the main and only entry point for all commands in the
  1771.     function table.  In order to respect state, such as whether the
  1772.     function is enabled or disabled, function table commands should
  1773.     never be called directly.
  1774.  
  1775.     If the function isn't in the function table and the ARexx message
  1776.     handler has been initialized, then the command is passed to ARexx.
  1777.  
  1778.    EXAMPLE
  1779.  
  1780.     /* how to call a function using its ID */
  1781.     PerfFunc (ai, QuitID, NULL, NULL);
  1782.  
  1783.     /* how to call a function using its name */
  1784.     PerfFunc (ai, NULL, "QUIT", NULL);
  1785.  
  1786.  
  1787.    INPUTS
  1788.     ai    - Pointer to the AppInfo structure
  1789.     fid    - ID of function to perform.
  1790.     cmdline    - Pointer to the text command line to use to trigger the
  1791.           command.
  1792.     attrs    - Pointer to the TagItem array to use to triggered the
  1793.           command.
  1794.  
  1795.    RESULT
  1796.     success    - Returns TRUE if the function was performed, FALSE if
  1797.           it didn't.
  1798.  
  1799. appshell.library/PrepText                           appshell.library/PrepText
  1800.  
  1801.    NAME
  1802.     PrepText - Obtain a pointer to a temporarily modifiable text message.
  1803.  
  1804.    SYNOPSIS
  1805.     text = PrepText(ai, base, id, args, ...)
  1806.     D0        D0  D1    A0  A1
  1807.  
  1808.     STRPTR text;
  1809.     struct AppInfo *ai;
  1810.     ULONG base, id;
  1811.     int args;
  1812.  
  1813.    FUNCTION
  1814.     Build a temporary text message using a text table entry and the
  1815.     passed arguments.  The text table entry must contain valid
  1816.     RawDoFmt formatting commands.
  1817.  
  1818.     The text pointer is only valid until the next call to PrepText.
  1819.     There is one PrepText buffer per AppInfo, so each cloned AppShell
  1820.     has its own work buffer.  The string must be copied to a more
  1821.     permanent storage place if you wish to keep it for a longer period.
  1822.  
  1823.     The main use for this function is for formatting of temporary
  1824.     error messages.
  1825.  
  1826.    EXAMPLE
  1827.  
  1828.     /* set up error return values */
  1829.     ai->ai_Pri_Ret = RETURN_FAIL;
  1830.     ai->ai_Sec_Ret = APSH_PORT_ACTIVE;
  1831.  
  1832.     /* "%s port already active", pname */
  1833.     ai->ai_TextRtn = PrepText(ai, APSH_MAIN_ID, ai->ai_Sec_Ret, pname);
  1834.  
  1835.  
  1836.    INPUTS
  1837.     ai    - Pointer to the AppInfo structure for this application.
  1838.     base    - Text table to use.
  1839.  
  1840.           APSH_USER_ID for the application text table.
  1841.           APSH_MAIN_ID for the AppShell text table.
  1842.           or may provide a custom message handler base ID.
  1843.  
  1844.     id    - Text Table entry id.
  1845.     args    - Variables to be sprintf'ed into the text entry.
  1846.  
  1847.    SEE ALSO
  1848.     GetText()
  1849.  
  1850. appshell.library/QStrCmpI                           appshell.library/QStrCmpI
  1851.  
  1852.    NAME
  1853.     QStrCmpI - Quick case insensitive string comparision.
  1854.  
  1855.    SYNOPSIS
  1856.     success = QStrCmpI (str1, str2)
  1857.     D0            D0    D1
  1858.  
  1859.     BOOL value;
  1860.     STRPTR str1, str2;
  1861.  
  1862.    FUNCTION
  1863.     This function performs a quick, case insensitive, string comparision.
  1864.     Stops as soon as it determines that the strings are not the same.
  1865.  
  1866.    EXAMPLE
  1867.  
  1868.     /* sample code fragment showing how to use QStrCmpI */
  1869.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1870.     {
  1871.         STRPTR name;
  1872.         STRPTR argv[MAXARG], clone=NULL;
  1873.         ULONG argc;
  1874.  
  1875.         /* make sure we have a command line */
  1876.         if (cmd)
  1877.         {
  1878.         /* parse the command line */
  1879.         clone = BuildParseLine (cmd, &argc, argv);
  1880.  
  1881.         /* make sure we have some arguments */
  1882.         if (argc >= 2L)
  1883.         {
  1884.             /* check to see if the first argument is CLOSE.
  1885.              * Note that FindType(argv, "CLOSE", NULL) could also be
  1886.              * used in this example.
  1887.              */
  1888.             if (QStrCmpI (argv[1], "CLOSE"))
  1889.             {
  1890.             /* do something because of CLOSE */
  1891.             }
  1892.         }
  1893.         }
  1894.  
  1895.         /* free the BuildParseLine */
  1896.         FreeParseLine (clone);
  1897.     }
  1898.  
  1899.    INPUTS
  1900.     str1     - Pointer to the first string.
  1901.     str2     - Pointer to the second string.
  1902.  
  1903.    RESULTS
  1904.     value     - TRUE if the strings are the same, otherwise returns FALSE.
  1905.  
  1906. appshell.library/RemoveMsgPort                 appshell.library/RemoveMsgPort
  1907.  
  1908.    NAME
  1909.     RemoveMsgPort - Safely remove a message port.
  1910.  
  1911.    SYNOPSIS
  1912.     RemoveMsgPort (mp)
  1913.                D0
  1914.  
  1915.     struct MsgPort *mp;
  1916.  
  1917.    FUNCTION
  1918.     This function will remove and reply to all messages that are
  1919.     outstanding on a message port before removing the port itself.
  1920.  
  1921.     NULL is a valid argument.
  1922.  
  1923.    INPUTS
  1924.     mp    - A pointer to the message port to delete.
  1925.  
  1926. appshell.library/RemoveProject                 appshell.library/RemoveProject
  1927.  
  1928.     NAME
  1929.     RemoveProject - Remove a project node from the project list.
  1930.  
  1931.     SYNOPSIS
  1932.     success = RemoveProject (ai, name, attrs)
  1933.     D0             D0  D1    A0
  1934.  
  1935.     BOOL success;
  1936.     struct AppInfo *ai;
  1937.     STRPTR name;
  1938.     struct TagItem *attrs;
  1939.  
  1940.     FUNCTION
  1941.     Removes a project node of the given name from the requested project
  1942.     list.  Defaults to removing the current project node from the main
  1943.     project list.
  1944.  
  1945.     Valid TagItems are:
  1946.  
  1947.         APSH_ProjInfo, <project>
  1948.         Where <project> is a valid pointer to a Project structure.
  1949.         Defaults to the AppInfo project structure.
  1950.  
  1951.         APSH_NameTag, <name>
  1952.         Where <name> is a valid project name to be removed.
  1953.  
  1954.     INPUTS
  1955.     ai    - Pointer to the application AppInfo structure.
  1956.     name    - Pointer to the name of the project to be removed.
  1957.     attrs    - Pointer to an optional TagItem array.
  1958.  
  1959.     RESULT
  1960.     TRUE    - Able to remove the project from the list.
  1961.     FALSE    - Unable to remove the project.
  1962.  
  1963.     BUGS
  1964.     name is not currently implemented.  Just removes the current project.
  1965.  
  1966. appshell.library/RenumProject                   appshell.library/RenumProject
  1967.  
  1968.     NAME
  1969.     RenumProject - Renumber the project list.
  1970.  
  1971.     SYNOPSIS
  1972.     RenumProject (ai, cmd, attrs)
  1973.               D0  D1    A0
  1974.  
  1975.     struct AppInfo *ai;
  1976.     STRPTR cmd;
  1977.     struct TagItem *attrs;
  1978.  
  1979.     FUNCTION
  1980.     Renumbers the project list.
  1981.  
  1982.     Valid TagItems are:
  1983.  
  1984.         APSH_ProjInfo, <project>
  1985.         Where <project> is a valid pointer to a Project structure.
  1986.         Defaults to the AppInfo project structure.
  1987.  
  1988.     INPUTS
  1989.     ai    - Pointer to the application AppInfo structure.
  1990.     cmd    - Pointer to the command string.
  1991.     attrs    - Pointer to the TagItem array.
  1992.  
  1993. appshell.library/setup_arexxA                   appshell.library/setup_arexxA
  1994.  
  1995.    NAME
  1996.     setup_arexxA - Initializes the ARexx message handler.
  1997.  
  1998.    SYNOPSIS
  1999.     mh = setup_arexxA (ai, tags)
  2000.     D0        D0  D1
  2001.  
  2002.     struct MsgHandler *mh;
  2003.     struct AppInfo *ai;
  2004.     struct TagItem *tags;
  2005.  
  2006.    FUNCTION
  2007.     This is the low-level function used to initialize the ARexx message
  2008.     hander.
  2009.  
  2010.     NOTE: This call should not be called directly by the application,
  2011.     but should invoked by using the APSH_AddARexx_UI tag.
  2012.  
  2013.     Valid tagitems to use at INITIALIZATION are:
  2014.  
  2015.         APSH_ARexxError, <id>
  2016.         ID of the function to call whenever an ARexx message returns
  2017.         with an error.
  2018.  
  2019.         APSH_ARexxOK, <id>
  2020.         ID of the function to call whenever an ARexx message returns
  2021.         successfully.
  2022.  
  2023.         APSH_Extens, <extension>
  2024.         Used to specify the default macro file extension to use.
  2025.         Defaults to .REXX
  2026.  
  2027.         APSH_Port, <name>
  2028.         Used to specify a name for the ARexx port.  Defaults to
  2029.         APSH_BaseName.
  2030.  
  2031.         APSH_Status, <flags>
  2032.         Where flags can be:
  2033.  
  2034.         APSHP_INACTIVE
  2035.         When set, then the ARexx port will be initialized, but
  2036.         will fail all messages received.
  2037.  
  2038.         APSHP_SINGLE
  2039.         When set, will not add a use count to the end of the
  2040.         ARexx port name.
  2041.  
  2042.     In addition to the standard message handler functions, the ARexx
  2043.     function handler provides the following functions:
  2044.  
  2045.         AH_SENDCMD
  2046.         Send a command to ARexx.
  2047.  
  2048.    EXAMPLE
  2049.  
  2050.     /* To send an command to ARexx */
  2051.     struct MsgHandler *mh;
  2052.     STRPTR cmd;
  2053.  
  2054.     cmd = "\"ADDRESS COMMAND DIR\"";
  2055.  
  2056.     /* Get a pointer to the ARexx message handler */
  2057.     if (mh = HandlerData (ai, APSH_Handler, "AREXX", TAG_DONE))
  2058.     {
  2059.         /* Send the command to ARexx */
  2060.         retval = HandlerFunc (ai,
  2061.                   APSH_Handler, "AREXX",
  2062.                   APSH_Command, AH_SENDCMD,
  2063.                   APSH_CmdString, cmd,
  2064.                   TAG_DONE);
  2065.     }
  2066.  
  2067.  
  2068.    INPUTS
  2069.     ai    - Pointer to the application's AppInfo structure.
  2070.     tags    - Pointer to an array of TagItem attributes for the
  2071.           function.
  2072.  
  2073.    RESULT
  2074.     mh    - Pointer to a MsgHandler structure.
  2075.  
  2076.    SEE ALSO
  2077.  
  2078. appshell.library/setup_dosA                       appshell.library/setup_dosA
  2079.  
  2080.    NAME
  2081.     setup_dosA - Initializes the Command Shell message handler.
  2082.  
  2083.    SYNOPSIS
  2084.     mh = setup_dosA (ai, attrs)
  2085.     D0               D0  D1
  2086.  
  2087.     struct MsgHandler *mh;
  2088.     struct AppInfo *ai;
  2089.     struct TagItem *attrs;
  2090.  
  2091.    FUNCTION
  2092.     This is the low-level function used to initialize the Command
  2093.     Shell message handler.
  2094.  
  2095.     NOTE: This call should not be called directly by the application,
  2096.     but should invoked by using the APSH_AddCmdShell_UI tag.
  2097.  
  2098.     Valid tagitems to use at INITIALIZATION are:
  2099.  
  2100.         APSH_Status, <flags>
  2101.         Where flags can be:
  2102.  
  2103.         APSHP_INACTIVE
  2104.         When set, then the command shell will be initialized, but
  2105.         will remain closed until opened explicitly by the user.
  2106.  
  2107.         APSH_CloseMsg, <ID>
  2108.         Text ID of the message displayed when attempting to close the
  2109.         command shell.  Defaults to "Waiting for macro return".
  2110.  
  2111.         APSH_CMDWindow, <ID>
  2112.         Text ID of the console window spec.  A reasonable default spec
  2113.         is provided.
  2114.  
  2115.         APSH_Prompt, <ID>
  2116.         Text ID of the text to used for a prompt.  "Cmd> " is the default
  2117.         prompt.
  2118.  
  2119.         APSH_CMDTitle
  2120.         Used to specify the text ID of title for the Command Shell.  Defaults to
  2121.         <basename> Command Shell.
  2122.  
  2123.         APSH_ParentWindow
  2124.         APSH_CMDParent (obsolete, don't use).
  2125.         Used to specify the text ID the parent window of the Command Shell.
  2126.         Should be the main project window of the application.  Using this tag
  2127.         helps the AppShell keep the Command Shell near the application when the
  2128.         user is using a virtual screen.  Not fully implemented yet.
  2129.  
  2130.    INPUTS
  2131.     ai    - Pointer to the application's AppInfo structure.
  2132.     attrs    - Pointer to an array of TagItem attributes for the
  2133.           function.
  2134.  
  2135.    RESULT
  2136.     mh    - Pointer to a MsgHandler structure.
  2137.  
  2138.    SEE ALSO
  2139.  
  2140. appshell.library/setup_idcmpA                   appshell.library/setup_idcmpA
  2141.  
  2142.    NAME
  2143.     setup_idcmpA - Initializes the Intuition message handler.
  2144.  
  2145.    SYNOPSIS
  2146.     mh = setup_idcmpA (ai, attrs)
  2147.     D0           D0  D1
  2148.  
  2149.     struct MsgHandler *mh;
  2150.     struct AppInfo *ai;
  2151.     struct TagItem *attrs;
  2152.  
  2153.    FUNCTION
  2154.     This is the low-level function used to initialize the Intuition,
  2155.     or GUI, message handler.
  2156.  
  2157.     NOTE: This call should not be called directly by the application,
  2158.     but should invoked by using the APSH_AddIntui_UI tag.
  2159.  
  2160.     Valid tagitems to use at INITIALIZATION are:
  2161.  
  2162.         APSH_Status, <flags>
  2163.         Where flags can be:
  2164.  
  2165.         APSHP_INACTIVE
  2166.         When set, then the window environment, that is passed in
  2167.         with the initialization tags, will be not be initialized.
  2168.  
  2169.         The following tags allow the programmer to specify a function
  2170.         to be executed whenever the corresponding IDCMP event occurs.
  2171.  
  2172.         APSH_SizeVerify, <id>
  2173.         APSH_NewSize, <id>
  2174.         APSH_RefreshWindow, <id>
  2175.         APSH_MouseButtons, <id>
  2176.         APSH_ReqSet, <id>
  2177.         APSH_CloseWindow, <id>
  2178.         APSH_ReqVerify, <id>
  2179.         APSH_ReqClear, <id>
  2180.         APSH_MenuVerify, <id>
  2181.         APSH_DiskInserted, <id>
  2182.         APSH_DiskRemoved, <id>
  2183.         APSH_ActiveWindow, <id>
  2184.         APSH_InactiveWindow, <id>
  2185.         APSH_IntuiTicks, <id>
  2186.         APSH_MouseMove, <id>
  2187.  
  2188.         APSH_WinBOpen, <id>
  2189.         Function to execute before opening a window.
  2190.  
  2191.         APSH_WinAOpen, <id>
  2192.         Function to execute after opening a window.
  2193.  
  2194.         APSH_WinBClose, <id>
  2195.         Function to execute before closing a window.
  2196.  
  2197.         APSH_WinAClose, <id>
  2198.         Function to execute after closing a window.
  2199.  
  2200.         APSH_RefreshData, <id>
  2201.         Function to execute whenever the data for gadgets needs
  2202.         refreshing.  Because GadTools doesn't support relative
  2203.         gadgets, the AppShell has to free the gadgets and build new
  2204.         ones whenever the user resizes a sizeable window.
  2205.  
  2206.    INPUTS
  2207.     ai    - Pointer to the application's AppInfo structure.
  2208.     attrs    - Pointer to an array of TagItem attributes for the
  2209.           function.
  2210.  
  2211.    RESULT
  2212.     mh    - Pointer to a MsgHandler structure.
  2213.  
  2214.    SEE ALSO
  2215.  
  2216. appshell.library/setup_notifyA                 appshell.library/setup_notifyA
  2217.  
  2218.    NAME
  2219.     setup_notifyA - Initializes the notification message handler.
  2220.  
  2221.    SYNOPSIS
  2222.     mh = setup_notifyA (ai, attrs)
  2223.     D0                  D0  D1
  2224.  
  2225.     struct MsgHandler *mh;
  2226.     struct AppInfo *ai;
  2227.     struct TagItem *attrs;
  2228.  
  2229.    FUNCTION
  2230.     This is the low-level function used to initialize the file
  2231.     notification message handler.  This handler is responsible for
  2232.     dispatching events when marked files are modified.
  2233.  
  2234.     NOTE: This call should not be called directly by the application,
  2235.     but is automatically initialized by all AppShell applications.
  2236.  
  2237.     Valid tagitems to use at OPEN time:
  2238.  
  2239.         APSH_NameTag, <file name>
  2240.         Complete file name of file to watch.
  2241.  
  2242.         APSH_CmdID, <function ID>
  2243.         Function to execute when file is modified.  Examine APSH_NameTag
  2244.         to get the name of the file modified.
  2245.  
  2246.    NOTES
  2247.     This handler is used by the AppShell to automatically handle preference
  2248.     files, with notification, for the application.
  2249.  
  2250.     When the application closes, all notification events will be
  2251.     automatically terminated.
  2252.  
  2253.    EXAMPLE
  2254.  
  2255.     /* Start notification on a file */
  2256.     VOID WatchClipFile (struct AppInfo *ai, STRPTR cmd, struct TagItem *attrs)
  2257.     {
  2258.         /* Start the notification */
  2259.         HandlerFunc (ai,
  2260.              APSH_Handler,    "NOTIFY",
  2261.              APSH_Command,    APSH_MH_OPEN,
  2262.              APSH_NameTag,    "ram:temp",
  2263.              APSH_CmdID,    ClipFileChangeID,
  2264.              TAG_DONE);
  2265.     }
  2266.  
  2267.    INPUTS
  2268.     ai    - Pointer to the application's AppInfo structure.
  2269.     attrs    - Pointer to an array of TagItem attributes for the
  2270.           function.
  2271.  
  2272.    RESULT
  2273.     mh    - Pointer to a MsgHandler structure.
  2274.  
  2275.    SEE ALSO
  2276.  
  2277. appshell.library/setup_sipcA                     appshell.library/setup_sipcA
  2278.  
  2279.    NAME
  2280.     setup_sipcA - Initializes the SIPC message handler.
  2281.  
  2282.    SYNOPSIS
  2283.     mh = setup_sipcA (ai, attrs)
  2284.     D0                D0  D1
  2285.  
  2286.     struct MsgHandler *mh;
  2287.     struct AppInfo *ai;
  2288.     struct TagItem *attrs;
  2289.  
  2290.    FUNCTION
  2291.     This is the low-level function used to initialize the Simple
  2292.     InterProcess Communications message handler.
  2293.  
  2294.     NOTE: This call should not be called directly by the application,
  2295.     but should invoked by using the APSH_AddSIPC_UI tag.
  2296.  
  2297.     Valid tagitems to use at INITIALIZATION are:
  2298.  
  2299.         APSH_Port, <name>
  2300.         Used to specify a name for the SIPC port.  Defaults to
  2301.         APSH_BaseName plus _SIPC.
  2302.  
  2303.         APSH_Status, <flags>
  2304.         Where flags can be:
  2305.  
  2306.         APSHP_INACTIVE
  2307.         When set, then the port will be initialized, but
  2308.         will fail all messages received.
  2309.  
  2310.         APSHP_SINGLE
  2311.         When set, will not add a use count to the end of the
  2312.         message port name.
  2313.  
  2314.         APSH_SIPCOK, <func id>
  2315.         Function to execute when a SIPC message returns successfully.
  2316.  
  2317.         APSH_SIPCError, <func id>
  2318.         Function to execute when a SIPC message returns with an error.
  2319.  
  2320.         APSH_AlreadyRunning, <func id>
  2321.         Function to execute if port (when APSHP_SINGLE specified)
  2322.         already exists.
  2323.  
  2324.     In addition to the standard message handler functions, the SIPC
  2325.     function handler provides the following functions:
  2326.  
  2327.         AH_SENDCMD
  2328.         Send a command to another AppShell application.  This function
  2329.         understands the following tags:
  2330.  
  2331.         APSH_NameTag, <name>
  2332.         Name of the destination SIPC message port.
  2333.  
  2334.         APSH_PortAddr, <MsgPort *>
  2335.         Address of the destination SIPC message port.
  2336.  
  2337.         APSH_CmdID, <function ID>
  2338.         Function ID for the destination application to invoke.
  2339.  
  2340.         APSH_CmdData, <data>
  2341.         Information to send to the destination application.  Data
  2342.         can be a tag list or a block of data.
  2343.  
  2344.         APSH_CmdDataLength, <length>
  2345.         This is used to indicate a block of data.
  2346.  
  2347.         APSH_CmdString, <command>
  2348.         This is used to send a command string to another application.
  2349.  
  2350.    EXAMPLE
  2351.  
  2352.     STRPTR port_name;
  2353.     struct MsgPort *mp;
  2354.     struct TagItem *attr_list;
  2355.     LONG data;
  2356.     LONG data_len;
  2357.  
  2358.     /* To send a command string to another AppShell application */
  2359.     HandlerFunc (ai,
  2360.              APSH_Handler, "SIPC",
  2361.              APSH_Command, AH_SENDCMD,
  2362.              APSH_NameTag, port_name,
  2363.              APSH_CmdString, "window front activate",
  2364.              TAG_DONE);
  2365.  
  2366.     /* To call a function with tags */
  2367.     HandlerFunc (ai,
  2368.              APSH_Handler, "SIPC",
  2369.              APSH_Command, AH_SENDCMD,
  2370.              APSH_PortAddr, port_addr,
  2371.              APSH_CmdID, OpenID,
  2372.              APSH_CmdData, attr_list,
  2373.              TAG_DONE);
  2374.  
  2375.     /* To send a block of a data */
  2376.     HandlerFunc (ai,
  2377.              APSH_Handler, "SIPC",
  2378.              APSH_Command, AH_SENDCMD,
  2379.              APSH_PortAddr, ad->ad_ProjSIPC,
  2380.              APSH_CmdID, SendDataID,
  2381.              APSH_CmdData, data,
  2382.              APSH_CmdDataLength, data_len,
  2383.              TAG_DONE);
  2384.  
  2385.    INPUTS
  2386.     ai    - Pointer to the application's AppInfo structure.
  2387.     attrs    - Pointer to an array of TagItem attributes for the
  2388.           function.
  2389.  
  2390.    RESULT
  2391.     mh    - Pointer to a MsgHandler structure.
  2392.  
  2393.    SEE ALSO
  2394.  
  2395. appshell.library/setup_toolA                     appshell.library/setup_toolA
  2396.  
  2397.    NAME
  2398.     setup_toolA - Initializes the tool message handler.
  2399.  
  2400.    SYNOPSIS
  2401.     mh = setup_toolA (ai, attrs)
  2402.     D0                D0  D1
  2403.  
  2404.     struct MsgHandler *mh;
  2405.     struct AppInfo *ai;
  2406.     struct TagItem *attrs;
  2407.  
  2408.    FUNCTION
  2409.     This is the low-level function used to initialize the tool message
  2410.     handler.  This message handler is responsible for maintaining the
  2411.     initialization & shutdown of asynchronous processes within an
  2412.     application.
  2413.  
  2414.     NOTE: This call should not be called directly by the application,
  2415.     but should invoked by using the APSH_AddTool_UI tag.
  2416.  
  2417.     Valid tagitems to use at OPEN time:
  2418.  
  2419.         APSH_Tool, <name>
  2420.         Name to give to the process that is spawned.  Required.
  2421.  
  2422.         APSH_ToolData, <data>
  2423.         Data to pass to the new process.  Passes a pointer to the
  2424.         AppInfo structure as default.  If you are starting a new AppShell
  2425.         application, then a tag list should be passed.
  2426.  
  2427.         APSH_ToolAddr, <function>
  2428.         Pointer to the function to spawn as a new process.  Defaults to
  2429.         HandleAppAsync.
  2430.  
  2431.         APSH_ToolStack, <stack size>
  2432.         Stack size to allocate for the new process.  Defaults to 4096
  2433.         bytes.
  2434.  
  2435.         APSH_ToolPri, <priority>
  2436.         Priority to run the new process at.  Defaults to zero.
  2437.  
  2438.    EXAMPLE
  2439.  
  2440.     /* Start a project as a new process */
  2441.     VOID NewProject (struct AppInfo *ai, STRPTR cmd, struct TagItem *attrs)
  2442.     {
  2443.         extern struct TagItem Cloned_App[];
  2444.         struct MsgHandler *mh;
  2445.         struct TagItem *tag;
  2446.  
  2447.         /* Search for the tag to store our SIPC address in */
  2448.         if (tag = FindTagItem (APSH_PortAddr, Cloned_App))
  2449.         {
  2450.         /* See if we have a SIPC port */
  2451.         if (mh = HandlerData (ai, APSH_Handler, "SIPC", TAG_DONE))
  2452.         {
  2453.             /* Get the address of our SIPC port */
  2454.             tag->ti_Data = (ULONG) mh->mh_Port;
  2455.         }
  2456.         }
  2457.  
  2458.         /* Start the new process */
  2459.            HandlerFunc (ai,
  2460.              APSH_Handler,    "TOOL",
  2461.              APSH_Command,    APSH_MH_OPEN,
  2462.              APSH_Tool,    "MiniBuild_Project",
  2463.              APSH_ToolData, Cloned_App,
  2464.              TAG_DONE);
  2465.     }
  2466.  
  2467.    INPUTS
  2468.     ai    - Pointer to the application's AppInfo structure.
  2469.     attrs    - Pointer to an array of TagItem attributes for the
  2470.           function.
  2471.  
  2472.    RESULT
  2473.     mh    - Pointer to a MsgHandler structure.
  2474.  
  2475.    SEE ALSO
  2476.  
  2477. appshell.library/setup_wbA                         appshell.library/setup_wbA
  2478.  
  2479.    NAME
  2480.     setup_wbA - Initialize the Workbench message handler.
  2481.  
  2482.    SYNOPSIS
  2483.     mh = setup_wbA (ai, tags)
  2484.     D0        D0  D1
  2485.  
  2486.     struct MsgHandler *mh;
  2487.     struct AppInfo *ai;
  2488.     struct TagItem *tags;
  2489.  
  2490.    FUNCTION
  2491.     This is the low-level Workbench message handler function used to
  2492.     initialize the Workbench message hander.  This handles the AppIcon,
  2493.     AppWindow and AppMenuItem features of Workbench.
  2494.  
  2495.     NOTE: This call should not be called directly by the application,
  2496.     but should invoked by using the APSH_AddWB_UI tag.
  2497.  
  2498.     Valid tagitems to use at INITIALIZATION are:
  2499.  
  2500.         APSH_Status, <flags>
  2501.         Where flags can be APSHP_INACTIVE or NULL.
  2502.  
  2503.         Any of the OPEN tags can be used to make a Workbench object
  2504.         active immediately.
  2505.  
  2506.     Valid tagitems to use at OPEN are:
  2507.  
  2508.         These tags are used when adding a new entry to the Workbench
  2509.         message handler object list.
  2510.  
  2511.           APSH_AppWindowEnv, <tag array>
  2512.         Where <tag array> is a tag array that describes the
  2513.         AppWindow to add.
  2514.  
  2515.           APSH_AppIconEnv, <tag array>
  2516.         Not implemented.
  2517.  
  2518.           APSH_AppMenuEnv, <tag array>
  2519.         Not implemented.
  2520.  
  2521.         These tags are used to specify functions for a new entry in the
  2522.         Workbench message handler object list.
  2523.  
  2524.           APSH_AppOpen, <func ID>
  2525.         Function to call after the object is opened, whenever it is
  2526.         opened.
  2527.  
  2528.           APSH_AppBDrop, <func ID>
  2529.         Function to call when an AppMessage is received, before any
  2530.         further processing.
  2531.  
  2532.           APSH_AppDDrop, <func ID>
  2533.         Function to call for each WBArg in an AppMessage argument
  2534.         list.  The APSH_WBF_NOLIST must be set for this function
  2535.         to be called.
  2536.  
  2537.           APSH_AppADrop, <func ID>
  2538.         Function to call after the AppMessage has been processed.
  2539.  
  2540.           APSH_AppClose, <func ID>
  2541.         Function to call before closing a Workbench message handler
  2542.         object.
  2543.  
  2544.           APSH_AppRemove, <func ID>
  2545.         Function to call before removing a Workbench message handler
  2546.         object.
  2547.  
  2548.           APSH_AppDblClick, <func ID>
  2549.         Function to call when an AppIcon has been double-clicked.
  2550.  
  2551.    INPUTS
  2552.     ai    - Pointer to the application's AppInfo structure.
  2553.     tags    - Pointer to an array of TagItem attributes for the
  2554.           function.
  2555.  
  2556.    RESULT
  2557.     mh    - Pointer to a MsgHandler structure.
  2558.  
  2559.    SEE ALSO
  2560.  
  2561. appshell.library/SwapProjNodes                 appshell.library/SwapProjNodes
  2562.  
  2563.     NAME
  2564.     SwapProjNodes - Swap two project nodes within the same Project list.
  2565.  
  2566.     SYNOPSIS
  2567.     SwapProjNodes (ai, pn1, pn2, attrs)
  2568.                D0  D1   A0   A1
  2569.  
  2570.     struct AppInfo *ai;
  2571.     struct ProjNode *pn1;
  2572.     struct ProjNode *pn2;
  2573.     struct TagItem *attrs;
  2574.  
  2575.     FUNCTION
  2576.     This function will swap two project nodes within the same project
  2577.     list.
  2578.  
  2579.     Valid TagItems are:
  2580.  
  2581.         APSH_ProjInfo,<project>
  2582.         Where <project> is a valid pointer to a Project structure.
  2583.         Defaults to the AppInfo project structure.
  2584.  
  2585.     INPUTS
  2586.     ai    - Pointer to the application AppInfo structure.
  2587.     pn1    - Pointer to a valid ProjNode structure.
  2588.     pn2    - Pointer to a valid ProjNode structure.
  2589.     attrs    - Pointer to an optional TagItem array.
  2590.  
  2591. appshell.library/UnlockAppInfo                 appshell.library/UnlockAppInfo
  2592.  
  2593.    NAME
  2594.     UnlockAppInfo - Unlock a locked application context.
  2595.  
  2596.    SYNOPSIS
  2597.     UnlockAppInfo ( key );
  2598.             D0
  2599.  
  2600.     LONG key;
  2601.  
  2602.    FUNCTION
  2603.     This functions unlocks a locked application context.
  2604.  
  2605.    INPUTS
  2606.     key    - Key returned by LockAppInfo.
  2607.  
  2608.    SEE ALSO
  2609.     LockAppInfo()
  2610.  
  2611.